docs(client): README approval decisions are objects, and register carries its required name - #16926

Fixes #16210

The published README's namespace tour called approvals.approve / approvals.reject with a bare comment string. Both declare a decision object as the second parameter, so the comment was never going to arrive:

approve: async (requestId: string, decision?: { actorId?: string; comment?: string; attachments?: string[] }): Promise<ApprovalDecisionResult> => {
reject:  async (requestId: string, decision?: { actorId?: string; comment?: string; attachments?: string[] }): Promise<ApprovalDecisionResult> => {

Triage's reason for grading this p2 rather than cosmetic, kept in its own words:

⭐ JavaScript 读者：没有类型错误，评论被静默丢弃 —— 那个字符串被当作请求体发出去，而路由期望的是决策对象的字段。⇒ 审批被记下，理由消失，没有任何东西报错。

packages/client/package.json declares files: ["dist", "README.md", "CHANGELOG.md"], so this file is the npm front page of @objectstack/client.

Clause-②

Clause-②: no
— Re-declared from the delivered diff, not from the dispatch. The diff is packages/client/README.md
plus one changeset: prose narrowed back onto the signature the package already publishes. No accept
set is relaxed, no published surface gains a member, and no schema, export or type moved in either
direction. The auth.register correction is the same shape — the README now passes the name that
RegisterRequestSchema has always declared required; the contract did not move, the example did.

Located by symbol, never by line

The card cites :4686 / :4699 and triage recorded those rotted to "around :5283". They have rotted again: on origin/main @ ed6579b53b the symbols sit at packages/client/src/index.ts:5293 (approve) and :5306 (reject). Both were found by symbol. The README fence was located by content (the client.approvals.approve( call), not by offset.

The executable acceptance — both directions

Harness: the fence is extracted from packages/client/README.md by content, wrapped in an async function, and type-checked against the package's own built declarations (packages/client/dist/index.d.ts) after pnpm --filter '@objectstack/client...' build (green, 419s under the shared verify lock). Placeholders the prose uses without declaring are typed from the declarations themselves so they stay neutral: requestId/id/userId as string, batchRequest as the exported BatchUpdateRequest, fileData as unknown (the upload parameter is any).

Pre-fix — RED (tsc exit 2). Verbatim:

packages/client/.tscheck-16210/tour.ts(31,30): error TS2345: Argument of type '{ email: string; password: string; }' is not assignable to parameter of type '{ email: string; password: string; name: string; image?: string | undefined; }'.
  Property 'name' is missing in type '{ email: string; password: string; }' but required in type '{ email: string; password: string; name: string; image?: string | undefined; }'.
packages/client/.tscheck-16210/tour.ts(46,45): error TS2559: Type '"LGTM"' has no properties in common with type '{ actorId?: string | undefined; comment?: string | undefined; attachments?: string[] | undefined; }'.
packages/client/.tscheck-16210/tour.ts(47,44): error TS2559: Type '"Incomplete"' has no properties in common with type '{ actorId?: string | undefined; comment?: string | undefined; attachments?: string[] | undefined; }'.

Post-fix — GREEN. Re-generated from the corrected README and re-run unchanged, at final commit aaff32ce65:

FINAL_TSC_EXIT=0
fence: README lines 222..291 (opener/closer), 68 body lines
calls in fence: 35

The harness lived in an untracked scratch directory and was removed; git status is clean and it is not in this diff.

Whole-fence sweep — 35 calls, not 2

Per triage's instruction to widen the reading without widening the diff, every call in the fence went through the same .d.ts check, not just the two the card reports. Three hits, classified:

Hit 3 is the one the card did not report, and it is the same defect class, not #16142's: auth.register exists and is called with the wrong argument shape. RegisterRequestSchema (packages/spec/src/api/auth.zod.ts) declares name: z.string() as required and packages/spec/src/api/auth.test.ts pins the rejection of a request without it, so the contract is settled upstream and the README was the copy left behind — the same asymmetry the card describes. Per the dispatch's rule for this class it is fixed in this PR rather than filed.

Zero for the other class, with its control. No call in the fence failed as a missing method (#16142's class, which #16212 already closed), so nothing was filed separately. That zero is a reading rather than a silence because the same harness, on the same text, fired three errors — hits 1-3 above are the control.

All three corrections are aligned to content/docs/api/client-sdk.mdx, which already carries the right spelling for both (:359-360 for the approvals pair, :350 for register). After the fix, all 35 calls in the fence type-check clean.

Docs drift — the bot declined to answer, so this is a hand sweep

The docs-drift bot returned a non-answer, not a pass:

⚠️ 1 changed file(s) yielded no anchor (packages/client/README.md), so the pages documenting them are NOT COVERED by this run — this is not a clean bill of health for those files.

A README yields no symbol/route/SDK anchor, so that zero is definitional rather than measured. It is replaced here by a hand sweep taken on this branch at aaff32ce65 — ⛔ not treated as a pass. The alignment note above answers "is the docs page right?"; this section answers the different question "does any other page carry the same wrong shape?".

Query — a decision call whose second argument opens with a quote, i.e. the exact defect this card fixes:

grep -rnE "approvals\.(approve|reject)\([^,)]+,\s*['\"]"

Result: 0 hits on content/. 0 hits repo-wide (excluding node_modules, dist, .git).

Two controls, so that zero is a reading and not a dead grep:

1. The corpus is reached. The shape-agnostic form of the same query over content/ returns content/docs/api/client-sdk.mdx:359-360 — the card's own reference spelling, already correct. The query demonstrably walks the docs corpus.
2. The regex fires. The wrong-shape regex above, run unchanged against the pre-fix README (git show ed6579b53b:packages/client/README.md), matches lines 255-256. So a zero elsewhere means "no wrong shape", not "broken pattern".

Every approvals.approve / .reject site on this tree, read out rather than counted:

• content/docs/api/client-sdk.mdx:359-360 — already correct object form (this is control leg 1).
• packages/client/src/client.test.ts:783,798 — correct object form.
• packages/client/README.md:255-256 — the defect this PR fixes; now correct.
• Five CHANGELOG files carry client.approvals.approve(requestId, …) with the argument elided, so they assert no shape: packages/client, packages/runtime, packages/spec, packages/services/service-automation, packages/plugins/plugin-approvals.
• packages/rest/src/rest-route-ledger.ts:429-430 — ledger rows whose client: field holds the string 'approvals.approve'; not calls.
• docs/qa/platform-checklist/** — approvals.approver-resolution-matrix, an unrelated identifier matched on substring only.

And for hit 3's method, every auth.register site:

• content/docs/permissions/authentication.mdx:213 and :1009 — both multi-line calls, both carry name: 'John Doe'. Correct.
• content/docs/api/client-sdk.mdx:350 — correct.
• packages/client/src/client.test.ts:822 — carries name: 'Test User'. Correct.
• packages/plugins/plugin-auth/src/auth-route-ledger.ts:169 — ledger row, not a call.
• packages/cli/src/commands/register.ts:128 — not a docs site; recorded under 验收备注 below.

⇒ content/ carries no second instance of either defect.

One difference from the PM's reading, reported rather than reconciled silently. The PM read four CHANGELOGs at origin/main@9a89a0040d; this tree at aaff32ce65 has five. The two readings agree on the substance — the elided (requestId, …) form asserts no argument shape either way — and the discrepancy is a file count in a corpus that grows per release, taken on two different commits. The five is the number measured on the tree this PR delivers.

File surface

• packages/client/README.md — the only content change.
• .changeset/client-readme-approvals-decision-object.md — @objectstack/client patch. The README is a published file of this package, so the published artifact moves even though no code does; the changeset body says so.

packages/client/src/index.ts was READ ONLY — opened only to locate the approve / reject symbols and the register signature. It is held by open PR #16761 and is not in this diff. No source change was needed, so the stop-and-report condition for a widening diff never triggered.

No governed surface is in the diff: no docs/adr/**, no .claude/**, no skills/**, no AGENTS.md, no CLAUDE.md. No content/docs/releases/ page is touched — this PR's only input to the release notes is its changeset.

The missing gate is not touched: that this whole fence sits in check:published-readme-exports's NOT read bucket is #16209's subject, already filed and measured.

Gates

Derived with node scripts/pm/dispatch-gates.mjs --commands --repo objectstack-ai/objectstack from the real change set (2 paths, three-dot against the merge base), re-derived identically after git fetch origin main.

47 derived families, 47 run, 0 NOT-MEASURED, 0 UNRUN — reconciled with --ran:

dispatch-gates --ran: 47 derived famil(ies) accounted for — 47 run, 0 NOT-MEASURED.

Two of the 47 first came back PREREQUISITE NOT MET (check:skill-examples, check:dual-build-cjs-loads) because they read built output the worktree did not yet have. That is not a red and not a pass — nothing was measured. A full pnpm build --concurrency=2 (73/73 tasks successful, under the shared verify lock) was run and both were re-run properly:

GATE30_EXIT=0   pnpm --filter @objectstack/spec run check:skill-examples
  258 prose examples type-check across 3 surface(s)
GATE36_EXIT=0   pnpm check:dual-build-cjs-loads
  104 published require entry point(s) across 67 package(s) load

Check Changeset's subject is satisfied: this PR adds exactly one changeset, which is what that job counts. check-changeset-no-major.mjs, check-empty-changeset.mjs, check:changeset-gate-self-tests and check:objectui-changeset are all green in the run above. check:nul-bytes is green, and both touched files were additionally swept by hand for control characters (grep -naP '[\x00-\x08\x0b\x0c\x0e-\x1f\x7f]', no hits).

node scripts/pm/check-clause2-carriers.mjs --pair 16926 exits 0: "the clause-② declaration is readable in the fixed spelling and both carriers agree, and its diff carries no widening tell."

Every exit code above was captured before any pipe.

验收备注

Two observations, both noted, not filed, each with its successor named:

• check:skill-examples (@objectstack/spec) already does the exact thing this card had to do by hand: it type-checks marked prose TypeScript against built declarations, and it declares a client SDK (@objectstack/client-react, @objectstack/client) surface of 23 blocks. This README fence is not among them, which is why nothing caught either defect. Successor: the seat that works [finding] check:published-readme-exports cannot see any call in packages/client/README.md's namespace tour — the receiver is built by new, so ~30 documented calls on the npm front page are ungraded #16209 — that card owns "this fence is ungraded", and this is a concrete note about which existing machinery could grade it. ⛔ Deliberately not acted on here: building or repairing the gate is [finding] check:published-readme-exports cannot see any call in packages/client/README.md's namespace tour — the receiver is built by new, so ~30 documented calls on the npm front page are ungraded #16209's subject and would take this card past its class. No new card, because filing one would duplicate [finding] check:published-readme-exports cannot see any call in packages/client/README.md's namespace tour — the receiver is built by new, so ~30 documented calls on the npm front page are ungraded #16209.

• packages/cli/src/commands/register.ts:128 calls client.auth.register(registerPayload as any), where registerPayload is locally typed { email: string; password: string; name?: string } and the prompt reads Name (optional): — so an empty answer sends { email, password }. The spec declares name required, so the CLI's local type diverges from the contract and the as any is the only reason it compiles; drop the cast and it fails TS2345, the same error hit 3 just fixed in the README. ⛔ Not fixed here (outside this card's file surface) and not filed: RegisterRequestSchema is parsed at no door — it is a type-only contract, and the live route is better-auth's /sign-up/email, whose own validation was not measured — so there is no reproduction and no failing runtime probe, which makes this un-rehearsed drift rather than a reproducible defect. A targeted dedup search returned zero open cards, with a control that fired (a known-hitting query returned 14 with docs: packages/client/README.md calls approvals.approve(requestId, 'LGTM') — the second parameter is a decision object, so the npm front page fails with TS2559 #16210 top). Successor: the domain:cli seat, which owns this file. Surfaced to the PM in the structured report so the decision to file is theirs.

Nothing else was found. No dead code, naming or polish observations arose from this diff.

Generated by Claude Code